home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / text / manipulation / cv.lha / cv / cvt.doc next >
Encoding:
Text File  |  1993-12-31  |  10.2 KB  |  216 lines
  1.  
  2.      CV/CVT                                                    -*- Text -*-
  3.  
  4.      NAME
  5.           cvt - file converter command
  6.  
  7.      SYNOPSIS
  8.           cvt [options] [-f rulefile] [-o outfile] [@] [infiles]
  9.  
  10.      DESCRIPTION
  11.           Cvt converts given input files `infiles' to `outfile' using the
  12.           conversion rules given in `rulefile'.
  13.           The input and output filenames are optional.  If not specified
  14.           Cvt will use the standard input and/or output streams.
  15.  
  16.           If no rulefile is specified or if the rulefiles is empty cvt will
  17.           print a warning and copy the input data to the output stream
  18.           without changing anything.  Please note that the `-f' option
  19.           is allowed to appear only once in the command line.  This avoids
  20.           confusion with option keyword precedence and similar things.
  21.  
  22.           Input and output filename can be the same.  Cvt will always make
  23.           use of a temporary file when not writing to stdout.  The output
  24.           filename can be given relative to the input filename by using
  25.           one `%s' construct in the ouput filename specification.  The first
  26.           occurence of `%s' will be replaced by the input filename.
  27.           A constant output filename makes no sense with more than one input
  28.           file because cvt would replace this file each time a new input file
  29.           is converted.
  30.  
  31.           White spaces between the option keywords and their values are
  32.           optional, i.e. `-ofile' and `-o file' are both legal, concatenation
  33.           of option keywords however is not:  -nx and -n -x result in a quite
  34.           different behaviour.
  35.  
  36.  
  37.           Further options are:
  38.  
  39.           -c n     Sets the #of characters in local charset to n.
  40.                    (default is -c256)
  41.  
  42.           -E file  Directs error messages (e.g. from the rulefile scanner)
  43.                    to `file' instead of the standard error stream 'stderr'.
  44.                    Usefull for batchfiles together with `-n'.
  45.  
  46.           -e n     Sets the #of errors until the scanner aborts scanning
  47.                    rules.  (default is -e5)
  48.  
  49.           -l file  Cvt will take the input filenames from a file.
  50.                    Filenames in such a file must be seperated by white
  51.                    characters and can be quoted with double quotes `"'.
  52.                    There can be no further options in such files.
  53.  
  54.           -n       Cvt tries to parse all rules but won't convert anything.
  55.                    Usefull to check conversion scripts (rulefiles).
  56.                    If no `-f' option is given cvt will treat the intput
  57.                    files as script files and tries to parse them respectively.
  58.                    The explicit use of the `-f' keyword however makes cvt
  59.                    check only the script file.  Input filenames (if any)
  60.                    are ignored then.
  61.  
  62.           -t file  Sets the filename for the temporary output to 'file'.
  63.                    This file will also be used when converting to stdout.
  64.                    (Cvt would normally not write to a temporary file when
  65.                    converting to stdout)
  66.  
  67.           -x       Cvt checks the existance of all input filenames specified
  68.                    after (right of) this option before the conversion begins.
  69.  
  70.           A rulefile is a textfile conataining zero or more rules of the
  71.           form
  72.                                    lhs -> rhs ;
  73.  
  74.           with lhs and rhs being the left hand side and right hand side of
  75.           a conversion rule.
  76.  
  77.           The lhs holds 1 or more character codes which (if found in the
  78.           input stream) will be transformed to those in the rhs.  Lhs and
  79.           rhs don't need to be of equal length.  The rhs may even be empty
  80.           if all appearences of the lhs should be removed from the input.
  81.           Neither lhs nor rhs nor the number of rules is limited by cvt.
  82.  
  83.           Character codes are positive interger values in [0..C] with C
  84.           being the #of characters in the local charset (normally 256).
  85.           This value can be changed with the `-c' option in the command
  86.           line.  Character codes can be in decimal, hexadeximal or octal
  87.           notation.  Hex numbers must have a leading dollar sign `$', octal
  88.           numbers must have a leading zero `0'.
  89.  
  90.           Warning:  A common mistake is to write decimal numbers with a
  91.           leading `0'.  This is only correct for numbers <= 7.
  92.  
  93.           Character codes can be concatenated using commata `,'.  In addition
  94.           to the numeric character code values the lhs and rhs can contain
  95.           strings.  A string is a sequence of zero or more characters between
  96.           opening and closing double quotes `"'.  A string may contain
  97.           special escape sequences using the backslash `\' as an escape
  98.           character
  99.  
  100.                    \n      newline           NL (LF)
  101.                    \t      horizontal tab    HT
  102.                    \v      vertical tab      VT
  103.                    \b      backspace         BS
  104.                    \r      carriage return   CR
  105.                    \f      form feed         FF
  106.                    \a      alert             BEL
  107.                    \\      backslash         \
  108.                    \?      question mark     ?
  109.                    \'      single quote      '
  110.                    \"      double quotes     "
  111.                    \0      integer 0         NUL
  112.                    \ooo    octal number      ooo
  113.                    \xhhh   hex number        hhh
  114.  
  115.           Strings are also concatenated by commata.  A concatenation between
  116.           strings and numeric character codes is allowed.  A cvt string has
  117.           no terminating null character.
  118.  
  119.           Warning:  A common mistake is to assume that there is no need for
  120.           a comma in a concatenation of strings because it isn't needed in C
  121.           code.  Cvt however needs a comma to concatenate strings.
  122.  
  123.           A rule ends with a semicolon `;'.  There can be several rules in
  124.           one line and one rule can be split across several lines. There
  125.           can even be comments inside of a rule.
  126.  
  127.           Cvt supports both C and C++ like comments.  A comment in C begins
  128.           with a slash `/' followed by an asterisk `*' and ends with a `*/'.
  129.           Nested comments are not allowed, i.e. a `*/' can not be inside
  130.           or part of a comment.  A comment in C++ (also called remark here)
  131.           begins with two slashes `//' and ends with the end of the line they
  132.           appear in.
  133.  
  134.      NOTES
  135.           Cvt will not check the existance of the output file.
  136.           If it exists cvt will blow it away without asking you.  Cvt also
  137.           assumes the existance of all dircetories in the output path.
  138.  
  139.           Cvt can take the path to your conversion script files out of
  140.           the environment variable CVSCRIPTS.  If the given rulefile
  141.           is not present relative to the current directory cvt will
  142.           prepend the pathname in CVTSCRIPTS to the given rulefile.
  143.           It is legal to assign CVSCRIPTS several pathnames seperated by
  144.           commata `,'.  Cvt will scan CVSCRIPTS from left to right.
  145.           Trailing slashes are optional.
  146.  
  147.           There is a difference in the use of filenames and the use of
  148.           redirectioning (or piping).  It is of course absolutely legal to
  149.           pipe your data through cvt but you should be aware of the fact that
  150.           the standard input and output streams are often non-binary streams
  151.           and might change or even corrupt your data before it reaches cvt.
  152.           The files opened by cvt are read and written in binary mode.
  153.  
  154.           It is not possible to replace a file using the pipe or
  155.           redirectioning because the use of '>' in your command line deletes
  156.           the destination file before cvt sees a byte of it.
  157.  
  158.           The values of escaped character constants in a string and the
  159.           number of digits needed to express them are limited to the local
  160.           charset size.  There will be no warning for a string like
  161.  
  162.                                       "\x100"
  163.  
  164.           in a charset with character codes in [$00..$FF].  Cvt reads in this
  165.           case
  166.  
  167.                                       $10,"0"
  168.  
  169.           which is absolutely okay.  The same applies to octal character codes
  170.           in strings.
  171.  
  172.           Not only the value but also the number of digits is limited.  This
  173.           allows you to write a literal digit after an escaped character
  174.           code as in
  175.  
  176.                                       "\0077"
  177.  
  178.           which will be interpreted as
  179.  
  180.                                        07,"7"
  181.  
  182.           in a charset where 3 octal digits are needed to express all
  183.           available character codes.  It is wise then always to use three
  184.           digits for the number when embedding a numeric constant in
  185.           a string using octal noatation.  The notation is hard enough to
  186.           read without having to worry about whether the character after a
  187.           constant is a digit or not.
  188.  
  189.           It is allowed to break a rule into several lines to make the
  190.           text neater.  (There is no limit for the width of a line and so
  191.           there is no other reason why one could feel like breaking lines.)
  192.           It is however not allowed to break strings or the derivation
  193.           token `->'.
  194.  
  195.      DISTRIBUTION
  196.           This version of CVT is NOT in the PUBLIC DOMAIN.  You can however
  197.           freely distribute it as long as the following is observed:
  198.  
  199.           - The program and documentation must be distributed together and
  200.             may not be modified in any way.  The only exception is that the
  201.             program and documentation may be compressed into an archive for
  202.             uploading to Bulletin Boards or for other electronic transmission.
  203.  
  204.           - The program is not to be used commercially or included in a
  205.             commercial package for profit unless written authorisation from
  206.             me is obtained first.
  207.             This version of CVT may be freely included on public domain library
  208.             disks or compilation disks provided only a small fee is charged for
  209.             the service.
  210.  
  211.      AUTHOR
  212.           Tobias Ferber, Goethestraße 32, 76135 Karlsruhe
  213.  
  214.           Earn:      ukjg@dkauni2.bitnet
  215.           InterNet:  ukjg@ibm3090.rz.uni-karlsruhe.de
  216.